Schema Changes from V8.1 through V8.33

The table below specifies elements added in schema versions 8.1 through 8.33.

TABLE 1-6 New Elements V8.1 to V8.33

New Element

Parent of

Child of

Comments

echeckRedeposit

litleTxnId

echeckOrEcheckToken

batchRequest

litleOnlineRequest

New transaction type for eCheck Redeposit attempts.

echeckRedepositResonse

litleTxnId

redepositCount

response

responseTime

message

postDate (Online only)

accountUpdater

batchResponse

litleOnlineResponse

Response message for eCheck Redeposits

echeckOrEcheckToken

 

echeckCredit echeckRedeposit echeckSale

echeckVerification

Allows the substitution of either the echeck or echeckToken elements

echeckVoid

litleTxnId

litleOnlineRequest

New transaction type to Void an eCheck Sale or halt attempts to auto-Redeposit

echeckVoidResponse

litleTxnId

response

responseTime

message

postDate

litleOnlineResponse

Response message for eCheck Voids

echeckToken

litletoken

routingNumber

accType

checkNum

echeckCredit

echeckRedeposit

echeckSale

echeckVerification

Used for eCheck Tokenization

echeckAccountSuffix

 

registerTokenResponse

tokenResponse

last 3 digits of eCheck account - returned with the token

cardOrToken

 

accountUpdate

Allows the substitution of either the card or token elements

originalToken

 

accountUpdateResponse

Used for Account Updater support for tokens

updatedToken

 

accountUpdateResponse

Used for Account Updater support for tokens

echeckAccountSuffix

 

registerTokenResponse

tokenResponse

Added for eCheck Tokenization

filtering

prepaid

international

authorization

sale

Parent of filtering switches

prepaid

 

filtering

Used to enable/disable Prepaid Card filtering per transaction depending upon configuration and value submitted.

Enum Values:

true or false

international

 

filtering

Used to disable International Card filtering per transaction.

reloadable

 

fundingSource

Indicates whether the Prepaid card is reloadable

prepaidCardType

 

fundingSource

Indicates the type of Prepaid card used. For example, Teen, Gift, Payroll, etc.

issureCountry

 

enhancedAuthResponse

Indicates the country of the Issuing bank.

cardProductType

 

enhancedAuthResponse

Indicates the type of card. Enum Values: UNKNOWN COMMERCIAL

CONSUMER

paypage

paypageRegistrationId

expDate

cardValidationNum

type

authorization

sale

Added the following added in V8.7:

captureGivenAuth

credit

forceCapture

Used to submit the Pay Page Registration ID with the Authorization or Sale transaction. The response message contains the token associated with the submitted ID.

paypageRegistrationId

 

paypage

registerTokenRequest

Generated by interaction with the Worldpay eProtect and used as a substitute for the token in the initial Authorization or Sale transaction.

You can also use this element in a Register Token request to obtain a token in advance of submitting an Authorization or Sale transaction.

accountUpdater

Note: This element already existed as a child of the eCheck response messages. New parents and children are in bold type.

originalAccountInfo

newAccountInfo

extendedCardResponse

newCardInfo

newCardTokenInfo

newTokenInfo

originalCardInfo

originalCardTokenInfo

originalTokenInfo

echeckSalesResponse

echeckCreditResponse

echeckVerificatinResponse

authorizationResponse

saleResponse

captureResponse

forceCaptureResponse

Used to provide info about automatic NOC updates.

(New) Used to provide updated card/token numbers in response messages - associated with the Automatic Account Updater service.

extendedCardResponse

code

message

acccountUpdater

 

code

 

extendedCardResponse

Extended Response Code returned with accountUpdater information, if applicable. Value is either 501 (Account was closed.) or 504 (Contact the cardholder for updated information.)

newCardInfo

type

number

expDate

accountUpdater

Contains child elements providing the updated information for the submitted card.

newCardTokenInfo

litleToken

type

expDate

bin

accountUpdater

Contains child elements providing the updated token information for the submitted token.

newTokenInfo

accType

litleToken

routingNum

accountUpdater

Contains child elements providing the updated token information for eCheck transactions.

originalCardInfo

type

number

expDate

accountUpdater

Contains child elements providing the original information for the updated card.

originalCardTokenInfo

litleToken

type

expDate

bin

accountUpdater

Contains child elements providing the original token information for the updated token.

originalTokenInfo

accType

litleToken

routingNum

accountUpdater

Contains child elements providing the updated token information for eCheck transactions.

recycling

recycleAdvice recycleEngineActive

authorizationResponse

saleResponse

 

recycleAdvice

nextRecycleTime

recycleAdviceEnd

recycling

 

nextRecycleTime

 

recycleAdvice

Provides the recommended date/time to recycle the declined Authorization/Sale.

recyclyAdviceEnd

 

recycleAdvice

Signifies the end of the recycling advice.

merchantData

campaign

affiliate

merchantGroupingId

authorization

captureGivenAuth

credit

forceCapture

sale

eCheckSale

eCheckCredit

 

campaign

 

merchantData

Used to sort transactions by marketing campaign

affiliate

 

merchantData

Used to sort transactions by affiliate sales

merchantGroupingId

 

merchantData

Used to sort transactions by merchant designated values

taxType

 

authorization

captureGivenAuth

credit

forceCapture

sale

Used by MCC9311 merchants to designate Tax Billing or Convenience Fee

actionReason

 

authReversal

Only allowed value: SUSPECT_FRAUD

recyclingRequest

recycleBy

recycleId

authorization

sale

 

recycleBy

 

recyclingRequest

Used to indicate who merchant or Worldpay) controls recycling of the transaction should it be declined. Also determines where the transaction is counted for the purposes of A/B testing.

recycleId

 

recyclingRequest

Can be used as an alternate to <orderId> in the recycling signature.

recycleEngineActive

 

recycling

 

actionReason

 

credit

Only allowed value: SUSPECT_FRAUD

When you include this optional element in an authReversal transaction, the information will be forwarded to MasterCard as part of the MasterCard eCommerce Fraud Alert program.

When you include this optional element in an credit transaction, the Worldpay eComm system uses the information to track potentially fraudulent transactions for future analysis

fraudFilterOverride

 

authorization

sale

Set to true to disable all filtering for the submitted transaction. This setting take precedence over all other filter override settings.

NOTE: This element is available only if you are using cnpAPI schema version 8.13 or above.

updateCardValidation
NumOnToken

litletoken

cardValidationNum

orderId

litleOnlineRequest

batchrequest

The parent element for the transaction type used to update a CVV2/CVC2/CID code stored temporarily on the Worldpay eComm platform.

updateCardValidatinNum
OnTokenresponse

litleTxnId

response

message

responseTime

orderId

litleOnlineResponse

batchResponse

The parent element for the Worldpay response to updateCardValidationNum OnToken transactions.

merchantData

campaign

affiliate merchantGroupingId

eCheckVerification

eCheckRedeposit

The merchantData element was already a child of a number of transaction types (see merchantData), but was added to these eCheck transactions in V8.15.

recycling

creditLitleTxnId

voidResponse

Contains a child element providing the Vantiv transaction Id of an associated credit transaction (see below).

creditLitleTxnId

 

recycling

The Vantiv transaction Id of the credit transaction automatically issued by the system when you use a Void transaction to halt the Recycling Engine, but the transaction is already approved and captured. (Auto-refund option must be enabled.)

surchargeAmount

 

authorization

authReversal

capture

captureGivenAuth

credit

forceCapture

sale

Use of the surchargeAmount element applies to Visa or MasterCard credit card payments only. Also, you are required to notify the card networks and Worldpay of your intent to applying surcharges at least 30 days prior to implementing the surcharges. Please consult your Worldpay Relationship Manager if you have additional questions.

terminalId

 

pos

Optional field for inclusion of POS Terminal Id.

debtRepayment

 

authorization

captureGivenAuth

forceCapture

sale

 

The debtRepayment element was added to the Authorization, Force Capture, Capture Given Auth, and Sale transactions. The new element should be set to true for Visa transaction that are debt repayments. The merchant must be either MCC 6012 or 6051.

activate

orderId

amount

orderSource

card or

virtualGiftCard

litleOnlineRequest

batchrequest

The parent for the transaction type that activates a Private Label Gift Card.

activateResponse

litleTxnId

orderId

response

responseTime

postDate (online only)

message

fraudResult

giftCardResponse

virtualGiftCardResponse

litleOnlineResponse

batchResponse

The parent of a response message for an activate transaction.

activateReversal

litleTxnId

litleOnlineRequest

batchrequest

The parent for the transaction type that reverses the activation of a Private Label Gift Card.

This transaction type is Online only.

activateReversalRes ponse

litleTxnId

orderId

response

responseTime

postDate (online only)

message

giftCardResponse

litleOnlineResponse

batchResponse

The parent of a response message for an activateReversal transaction.

balanceInquiry

orderId

orderSource

card

litleOnlineRequest

batchrequest

The parent for the transaction type that queries the available balance of a Private Label Gift Card.

balanceInquiryResponse

litleTxnId

orderId

response

responseTime

postDate (online only)

message

fraudResult

giftCardResponse

litleOnlineResponse

batchResponse

The parent of a response message for an balanceInquiry transaction.

deactivate

orderId

orderSource

card

litleOnlineRequest

batchrequest

The parent for the transaction type that deactivates a Private Label Gift Card.

deactivateResponse

litleTxnId

orderId

response

responseTime

postDate (online only)

message

fraudResult giftCardResponse

litleOnlineResponse

batchResponse

The parent of a response message for an deactivate transaction.

deactivateReversal

litleTxnId

litleOnlineRequest

batchrequest

The parent for the transaction type that reverses the deactivation of a Private Label Gift Card. This transaction type is Online only.

deactivateReversal
Response

litleTxnId

orderId

response

responseTime

postDate (online only)

message

giftCardResponse

litleOnlineResponse

batchResponse

The parent of a response message for an deactivateReversal transaction.

load

orderId

amount

orderSource

card

litleOnlineRequest

batchrequest

The parent for the transaction type that adds funds to a Private Label Gift Card.

loadResponse

litleTxnId

orderId

response

responseTime

postDate (online only)

message

fraudResult giftCardResponse

litleOnlineResponse

batchResponse

The parent of a response message for a load transaction.

loadReversal

litleTxnId

litleOnlineRequest

batchrequest

The parent for the transaction type that reverses the loading of a Private Label Gift Card. This transaction type is Online only.

loadReversalResponse

litleTxnId

orderId

response

responseTime

postDate (online only)

message

giftCardResponse

litleOnlineResponse

batchResponse

The parent of a response message for a loadReversal transaction.

unload

orderId

amount

orderSource

card

litleOnlineRequest

batchrequest

The parent for the transaction type that removes funds from a a Private Label Gift Card.

unloadResponse

litleTxnId

orderId

response

responseTime

postDate (online only)

message

fraudResult

giftCardResponse

litleOnlineResponse

batchResponse

The parent of a response message for an unload transaction.

unloadReversal

litleTxnId

litleOnlineRequest

batchrequest

The parent for the transaction type that reverses the unloading of a Private Label Gift Card.

This transaction type is Online only.

unloadReversalResponse

litleTxnId

orderId

response

responseTime

postDate (online only)

message

giftCardResponse

litleOnlineResponse

batchResponse

The parent of a response message for an unloadReversal transaction.

virtualGiftCard

accountNumberLength

giftCardBin

activate

Parent of child elements defining the Virtual Gift Card BIN and number length.

accountNumberLength

 

virtualGiftCard

Defines the length of the Virtual Gift Card number. The value must be an integer between 13 and 25.

giftCardBin

 

virtualGiftCard

Defines the BIN of the Virtual Gift Card. The value cannot exceed 10 digits.

virtualGiftCardResponse

accountNumber

cardValidationNumber

activateResponse

Parent of child elements defining the Virtual Gift Card account number and validation number.

giftCardResponse

availableBalance

beginningBalance

endingBalance

cashBackAmount

activateResponse

deactivateResponse

autorizationResponse

authReversalResponse

balanceInquiryResponse

captureGivenAuthResponse

captureResponse

creditResponse

deactivateResponse

deactivateReversalResponse

depositReversalResponse

forceCaptureResponse

loadResponse

loadReversalResponse

refundReversalResponse

saleResponse

unloadResponse

unloadReversalResponse

Provides details about the beginning, ending, and available balance on a Gift Card, as well as the cash back amount, if applicable.

beginningBalance

 

giftCardResponse

Defines the funds available on the Private Label Gift Card prior to the transaction.

endingBalance

 

giftCardResponse

Defines the funds available on the Private Label Gift Card after the transaction.

cashBackAmount

 

giftCardResponse

Defines the funds returned to the user in the form of cash.

createPlan

planCode

name

description

intervalType amount

numberOfPayments

trialNumberOfIntervals

trialIntervalType

active

litleOnlineRequest

batchrequest

The parent for the transaction type that creates payment plans.

createPlanResponse

litleTxnId

response message

responseTime

planCode

litleOnlineResponse

batchResponse

The parent of a response message for an createPlan transaction.

updatePlan

planCode

active

litleOnlineRequest

batchrequest

The parent for the transaction type that you use to activate/defective a Plan. Deactivating a Plan has no effect on existing Subscription that use the Plan, but prevents the use of the Plan with new subscriptions.

updatePlanResponse

litleTxnId

response

message

responseTime

planCode

litleOnlineResponse

batchResponse

The parent of a response message for an updatePlan transaction.

updateSubscription

subscriptionId

planCode

billToAddress

card, paypage, or token

billingDate

createDiscount

updateDiscount

deleteDiscount

createAddOn

updateAddOn

deleteAddOn

litleOnlineRequest

batchrequest

The parent for the transaction that updates the subscription information associated with a recurring payment. Using this transaction type you can change the Plan, card, billing information, and/or billing date. You can also create, update, or delete a Discount and/or an Add On.

updateSubscription
Response

litleTxnId

response

message

responseTime

subscriptionCode

tokenResponse

litleOnlineResponse

batchResponse

The parent of a response message for an updateSubscription transaction.

cancelSubscription

subscriptionId

litleOnlineRequest

batchrequest

The parent for the transaction that cancels a Subscription.

cancelSubscriptionResponse

subscriptionId

litleTxnId

response message

responseTime

litleOnlineResponse

batchResponse

The parent of a response message for an cancelSubscription transaction.

recurringRequest

subscription

authorization

sale

The parent of several child elements that define the number of payments and plan type of recurring transaction to be handled by the Worldpay Recurring Engine.

recurringResponse

subscriptionId

responseCode

responseMessage

authorizationResponse

saleResponse

The parent element providing information in response to a recurringRequest.

responseCode

 

recurringResponse

A response code related to a recurring request.

responseMessage

 

recurringResponse

The text message associated with the response code.

subscription

planCode

numberOfPayments

startDate

amount

recurringRequest

The parent of several child elements that define the number of payments and plan type of recurring transaction to be handled by the Worldpay Recurring Engine.

subscriptionId

 

recurringResponse

cancelSubscription

cancelSubscriptionResponse

updateSubscription

updateSubscriptionResponse

A Worldpay assigned identifier of the created Subscription.

planCode

 

subscription

updateSubscription

createPlan

updatePlan

updatePlanResponse

A merchant assigned code for a particular Plan.

active

 

createPlan

updatePlan

A flag to activate or deactivate a Plan. Deactivating a Plan has no effect on existing Subscription that use the Plan, but prevents the use of the Plan with new subscriptions. Valid values are true or false.

billingDate

 

updateSubscription

Used to define a new date for the recurring billing when the scheduled date need to be changed.

createDiscount

discountCode

name

amount

startDate

endDate

subscription

updateSubscription

The parent element for elements that define a new Discount applied to a Subscription.

updateDiscount

discountCode

name

amount

startDate

endDate

updateSubscription

The parent element for elements that define updates to an existing Discount applied to a Subscription.

deleteDiscount

discountCode

updateSubscription

The parent element used to delete a Discount associated with a Subscription.

createAddOn

addOnCode

name

amount

startDate

endDate

subscription

updateSubscription

The parent element for elements that define a new Add On applied to a Subscription.

updateAddOn

addOnCode

name

amount

startDate

endDate

updateSubscription

The parent element for elements that define updates to an existing Add On applied to a Subscription.

deleteAddOn

addOnCode

updateSubscription

The parent element used to delete an Add On associated with a Subscription.

advancedFraudChecks

threatMetrixSessionId

authorization

sale

Parent of the threatMetrixSessionId element

threatMetrixSessionId

 

advancedFraudChecks

A unique value assigned by the merchant used to retrieve the data analysis results from by ThreatMetrix.

advancedFraudResults

deviceReviewStatus

deviceReputationScore

fraudResults

The parent of elements that provide the results of the ThreatMetrix analysis.

deviceReviewStatus

 

advancedFraudResults

The status resulting from the analysis of the data collected by ThreatMetrix compared to the threshold settings of the merchant profile. Possible values are: pass, fail, review, and unavailable.

deviceReputationScore

 

advancedFraudResults

The score resulting from a comparison of the collected data against the threshold settings of the merchant profile. Valid values are between -100 and 100.

catLevel

 

pos

Used only for CAT transactions, the value must be: self service.

triggeredRule

 

advancedFraudResults

A triggered rule is one where the threshold is exceeded. The element can appear multiple times in the response, once for each triggered rule from the ThreatMetrix policy.

fraudCheck

advancedFraudChecks

 

Allows you to retrieve the Advanced Fraud results without introducing a Authorization or Sale transactions

mpos

ksn

formatId

encryptedTrack

track1Status

track2Status

authorization

captureGivenAuth

credit

forceCapture

registerTokenRequest

sale

Parent element for information related to Mobile POS transactions.

ksn

 

mpos

Defines the key serial number returned from the encrypting device.

formatId

 

mpos

Define the format of the encrypted track returned from the encrypting device.

encryptedTrack

 

mpos

The encrypted track data.

track1Status

 

mpos

Indicates if the Mobile POS device read the track 1 data.

track2Status

 

mpos

Indicates if the Mobile POS device read the track 1 data.

wallet

walletSourceType

walletSourceTypeId

authorization

sale

Used to support MasterPass transactions.

walletSourceType

 

wallet

Defines the source of the transaction information. The only allowed value is MasterPass.

walletSourceTypeId

 

wallet

The Id value returned from the MasterPass service.

secondaryAmount

 

authorization capture credit

captureGivenAuth echeckCredit echeckSale forceCapture sale

Defines the principal portion of the total amount when a convenience fee applied to the transaction by the merchant. for example, if the total charge is $105, with the principal amount being $100 and the convenience fee being $5, you must use $100 as the value for the secondaryAmount element. Supply the value in cents without a decimal point. For example, a value of 400 signifies $4.00.

applepay

data

header

signature

version

authorization

sale

registerTokenRequest

Used, when the merchant does not decrypt the PKPaymentToken, to designate Apple Pay as the method of payment and supply the components of the PKPaymentToken.

data

 

applepay

The payment data dictionary, BASE64 encoded string from the PKPaymentToken.

header

applicationData

ephemeralPublicKey

publicKeyHash

transactionId

applepay

 

applicationData

header

 

Provides the SHA-256 hash, hex encoded string of the original PKPaymentRequest of the Apple Pay transaction.

ephemeralPublicKey

header

 

Provides the BASE64 Encoded string of the ephemeral public key bytes from the Apple Pay transaction.

publicKeyHash

header

 

Provides the BASE64 Encoded string that is a hash of the merchant’s certificate public key bytes associated with the Apple Pay transaction.

transactionId

header

 

Provides the hexadecimal transaction identifier generated on the device for an Apple Pay transaction.

signature

 

applepay

The BASE64 encoded string signature of the payment and header data from the PKPaymentToken.

version

 

applepay

Provides version information about the payment token.

applepayResponse

applicationPrimaryA ccountNumber

applicationExpirationDate

currencyCode

transactionAmount

cardholderName

deviceManufacturerIdentifier

paymentDataType

onlinePaymentCryptogram

eciIndicator

authorizationResponse

saleResponse

registerTokenResponse

Includes information about the Apple Pay transaction.

applicationPrimaryA ccountNumber

 

applepayResponse

Defines the primary account number associated with the application.

applicationExpirationDate

 

applepayResponse

Defines expiration date of the application primary account number.

currencyCode

 

applepayResponse

The 3-character code for the currency used in the transaction.

transactionAmount

 

applepayResponse

The amount of the transaction.

cardholderName

 

applepayResponse

The name of the cardholder.

deviceManufacturerIdentifier

 

applepayResponse

Defines the manufacturer of the device originating the transaction.

paymentDataType

 

applepayResponse

Specifies the data type of the payment data associated with an Apple Pay transaction.

onlinePaymentCryptogram

 

applepayResponse

Specifies the BASE64 Encoded signature cryptogram associated with the Apple Pay transaction.

eciIndicator

 

applepayResponse

Specifies electronic commerce indicator associated with an Apple Pay/Google Pay transaction.

processingType

 

authorization captureGivenAuth forceCapture

sale

fraudCheck

You use this element to define a Visa transaction is intended to fund a

host-based prepaid product, a brokerage account, or an escrow account.

Other enum values used for card on file transactions.

networkTransactionId

 

authorizationResponse

saleResponse

Returned in response messages for Visa, MasterCard, and Discover transactions. Store the value to use in later recurring, installment, or card on file transactions.

originalNetworkTransactionId

 

authorization captureGivenAuth

sale

For Visa and Discover, include this element for recurring, installment, and card on file (after initial) transactions.

originalTransactionAmount

 

authorization captureGivenAuth

sale

For Discover, include this element for recurring payments (after initial) involving network tokens.

Note: Not used at this time.

foreignRetailerIndicator

 

capture

captureGivenAuth

forceCapture

sale

Must be present when the marketplace and retailer are not in the same region (country). A value of 'F' indicates that the retailer is located in a different country.

authIndicator

 

authorization

Required if you submit an Incremental Authorization, used by certain Travel and Entertainment (T&E) merchants. when final purchase amounts are unknown.

 

Other schema changes:

    • If you are enabled for American Express Advanced AVS, you can use the customerIpAddress element (child of cardholderAuthentication element) to submit the customer IP Address. At this time, American Express does not validate the IP Address.

    • Merchant initiate Authorization Reversals are supported for American Express transactions.

    • Three new country codes were added to the list of enumerations for the country element. The new codes are: BQ (Bonaire, Saint Eustatius and Saba), CW (Curacao), and SX (Dutch part od Sint Maarten).

    • The redepositCount element was removed from the echeckRedepositResponse. You can determine the redeposit count via the User Interface. This element was in schema version 8.1 only. It is not listed in the table above.

    • New enumeration value, recurringtel, added to the orderSource element. This enumeration is used only for eCheck recurring transactions initiated by telephone.

    • The maxDigits for amount element changed from 8 to 12.

    • The cardNumValidation element was added to the Register Token Request transaction (registerTokenRequest).

    • For CAT (Cardholder Activated Terminal) transactions, the capability element must be set to magstripe, the cardholderId element must be set to nopin, and the catLevel element must be set to self service.

    • New enumeration for <orderSource>, echeckppd. Use this value for eCheck PPD transactions (Prearranged Payment and Deposit Entries). This type of transaction occurs when a merchants receives a written authorization, including a voided paper check, from a consumer so that the merchant can debit the consumer account. These transactions can be single entry or recurring debits to a consumer's account.

    • New enumeration for <orderSource>, applepay. Use this value for Apple Pay transactions.

    • Change in maxLength of the authenticationValue element - from 32 to 56 characters.

    • New enumerations added to the processingType element to support recurring and installment card on file transactions. The new enumerations are: initialRecurring, and initialInstallment.

    • New enumerations added to the processingType element to support card on file transactions. The new enumerations are: initialCOF, merchantInitiatedCOF, and cardholderInitiatedCOF.